ComboBox|TreeMenu: Clarify :row|column-span-column

ComboBox and TreeMenu warned in the doc for :row-span-column that the
value must not exceed :wrap-width, but :wrap-width does not interact
with the number of rows; it’s the :column-span-column that’s relevant.

Also: Warn that spans must be > 0 for rows too, and that column spans <=
:wrap-width are also not useful for items at menu column positions > 0.

Finally, refer to items having spans, not values, as we were already
talking about values in the model (and rows in the menu).

diff --git a/gtk/gtkcombobox.c b/gtk/gtkcombobox.c
index 633099d8c3bae4c8db8326fa327db8bd2cb262d4..5937c2c8f9ba7d913e231ad963eaa12b7dc54835 100644 (file)
--- a/gtk/gtkcombobox.c
+++ b/gtk/gtkcombobox.c
@@ -687,11 +687,9 @@ gtk_combo_box_class_init (GtkComboBoxClass *klass)
    * GtkComboBox:row-span-column:
    *
    * If this is set to a non-negative value, it must be the index of a column
-   * of type %G_TYPE_INT in the model.
-   *
-   * The values of that column are used to determine how many rows a value in
-   * the list will span. Therefore, the values in the model column pointed to
-   * by this property must be greater than zero and not larger than wrap-width.
+   * of type %G_TYPE_INT in the model. The value in that column for each item
+   * will determine how many rows the item will span in the popup. Therefore,
+   * values in this column must be greater than zero.
    *
    * Since: 2.4
    */
@@ -710,10 +708,10 @@ gtk_combo_box_class_init (GtkComboBoxClass *klass)
    * GtkComboBox:column-span-column:
    *
    * If this is set to a non-negative value, it must be the index of a column
-   * of type %G_TYPE_INT in the model.
-   *
-   * The values of that column are used to determine how many columns a value
-   * in the list will span.
+   * of type %G_TYPE_INT in the model. The value in that column for each item
+   * will determine how many columns that item will span in the popup.
+   * Therefore, values in this column must be greater than zero, and the sum of
+   * an item’s column position + span should not exceed #GtkComboBox:wrap-width.
    *
    * Since: 2.4
    */

diff --git a/gtk/gtktreemenu.c b/gtk/gtktreemenu.c
index afc90bdf4c8b1d15d1be7c399de712a345a3e050..c62b5dfb246fbafedf7e9e427a2149bdb6c9c887 100644 (file)
--- a/gtk/gtktreemenu.c
+++ b/gtk/gtktreemenu.c
@@ -318,11 +318,9 @@ _gtk_tree_menu_class_init (GtkTreeMenuClass *class)
    * GtkTreeMenu:row-span-column:
    *
    * If this is set to a non-negative value, it must be the index of a column
-   * of type %G_TYPE_INT in the model.
-   *
-   * The values of that column are used to determine how many rows a value in
-   * the list will span. Therefore, the values in the model column pointed to
-   * by this property must be greater than zero and not larger than wrap-width.
+   * of type %G_TYPE_INT in the model. The value in that column for each item
+   * will determine how many rows that item will span in the popup. Therefore,
+   * values in this column must be greater than zero.
    *
    * Since: 3.0
    */
@@ -342,8 +340,11 @@ _gtk_tree_menu_class_init (GtkTreeMenuClass *class)
    * If this is set to a non-negative value, it must be the index of a column
    * of type %G_TYPE_INT in the model.
    *
-   * The values of that column are used to determine how many columns a value
-   * in the list will span.
+   * If this is set to a non-negative value, it must be the index of a column
+   * of type %G_TYPE_INT in the model. The value in that column for each item
+   * will determine how many columns that item will span in the popup.
+   * Therefore, values in this column must be greater than zero, and the sum of
+   * an item’s column position + span should not exceed #GtkTreeMenu:wrap-width.
    *
    * Since: 3.0
    */